The section describes the programming interface of the RTC HAL driver. More...

Data Structures
struct	rtc_hal_init_config_t

struct	rtc_hal_access_control_config_t

Functions
void	rtc_hal_init (rtc_hal_init_config_t *configs)
	Initializes the RTC module. More...

static void	rtc_hal_reset_reg_TSR (void)
	Resets the RTC Time Seconds Register (RTC_TSR). More...

static void	rtc_hal_reset_reg_TPR (void)
	Resets the RTC Time Prescaler Register (RTC_TPR). More...

static void	rtc_hal_reset_reg_TAR (void)
	Resets the RTC Time Alarm Register (RTC_TAR). More...

static void	rtc_hal_reset_reg_TCR (void)
	Resets the RTC Time Compensation Register (RTC_TCR). More...

static void	rtc_hal_reset_reg_CR (void)
	Resets the RTC Control Register (RTC_CR). More...

static void	rtc_hal_reset_reg_SR (void)
	Resets the RTC Status Register (RTC_SR). More...

static void	rtc_hal_reset_reg_LR (void)
	Resets the RTC Lock Register (RTC_LR). More...

static void	rtc_hal_reset_reg_IER (void)
	Resets the RTC Interrupt Enable Register (RTC_IER). More...

static void	rtc_hal_get_seconds (uint32_t *seconds)
	Reads the value of the time seconds counter. More...

static bool	rtc_hal_set_seconds (const uint32_t *seconds)
	Writes to the time seconds counter. More...

static void	rtc_hal_get_prescaler (uint16_t *prescale)
	Reads the value of the time prescaler. More...

static bool	rtc_hal_set_prescaler (const uint16_t *prescale)
	Sets the time prescaler. More...

static void	rtc_hal_get_alarm (uint32_t *seconds)
	Reads the value of the time alarm. More...

static void	rtc_hal_set_alarm (const uint32_t *seconds)
	Sets the time alarm, this clears the time alarm flag. More...

static void	rtc_hal_get_comp_intrvl_counter (uint8_t *counter)
	Reads the compensation interval counter value. More...

static void	rtc_hal_get_current_time_compensation (uint8_t *tcValue)
	Reads the current time compensation interval counter value. More...

static void	rtc_hal_get_compensation_interval (uint8_t *value)
	Reads the compensation interval. More...

static void	rtc_hal_set_compensation_interval (const uint8_t *value)
	Writes the compensation interval. More...

static void	rtc_hal_get_time_compensation (uint8_t *value)
	Reads the time compensation value which is the configured number of the 32.768 kHz clock cycles in each second. More...

static void	rtc_hal_set_time_compensation (const uint8_t *enable)
	Writes to the RTC Time Compensation Register (RTC_TCR), field Time Compensation Register (TCR). More...

static void	rtc_hal_config_osc_2pf_load (bool enable)
	Enables/disables oscillator configuration for 2pF load. More...

static void	rtc_hal_config_osc_4pf_load (bool enable)
	Enables/disables oscillator configuration for 4pF load. More...

static void	rtc_hal_config_osc_8pf_load (bool enable)
	Enables/disables oscillator configuration for 8pF load. More...

static void	rtc_hal_config_osc_16pf_load (bool enable)
	Enables/disables oscillator configuration for 16pF load. More...

static void	rtc_hal_config_clock_out (bool enable)
	Enables/disables the 32kHz clock output to other peripherals. More...

static void	rtc_hal_config_oscillator (bool enable)
	Enables/disables the oscillator. More...

static void	rtc_hal_configure_update_mode (bool lock)
	Enables/disables the update mode. More...

static void	rtc_hal_configure_supervisor_access (bool enable_reg_write)
	Enables/disables the supervisor access, which configures non-supervisor mode write access to all RTC registers and non-supervisor mode read access to RTC tamper/monotonic registers. More...

static void	rtc_hal_software_reset (void)
	Performs a software reset on the RTC module. More...

static void	rtc_hal_software_reset_flag_clear (void)
	Clears the software reset flag. More...

static bool	rtc_hal_is_counter_enabled (void)
	Reads the time counter enabled/disabled status. More...

static void	rtc_hal_counter_enable (bool enable)
	Changes the time counter enabled/disabled status. More...

static bool	rtc_hal_is_alarm_occured (void)
	Checks if the configured time alarm occurred. More...

static bool	rtc_hal_is_counter_overflow (void)
	Checks whether a counter overflow happened. More...

static bool	rtc_hal_is_time_invalid (void)
	Checks whether the time is marked as invalid. More...

static void	rtc_hal_config_lock_registers (hw_rtc_lr_t bitfields)
	Configures the register lock to other module fields. More...

static bool	rtc_hal_get_lock_reg_lock (void)
	Obtains the lock status of the lock register. More...

static void	rtc_hal_set_lock_reg_lock (bool set_to)
	Changes the lock status of the lock register. More...

static bool	rtc_hal_get_status_reg_lock (void)
	Obtains the state of the status register lock. More...

static void	rtc_hal_set_status_reg_lock (bool set_to)
	Changes the state of the status register lock. More...

static bool	rtc_hal_get_control_reg_lock (void)
	Obtains the state of the control register lock. More...

static void	rtc_hal_set_control_reg_lock (bool set_to)
	Changes the state of the control register lock. More...

static bool	rtc_hal_get_time_comp_lock (void)
	Obtains the state of the time compensation lock. More...

static void	rtc_hal_set_time_comp_lock (bool set_to)
	Changes the state of the time compensation lock. More...

static void	rtc_hal_config_interrupts (hw_rtc_ier_t *bitfields)
	Enables/disables RTC interrupts. More...

static bool	rtc_hal_read_seconds_int_enable (void)
	Checks whether the Time Seconds Interrupt is enabled/disabled. More...

static void	rtc_hal_config_seconds_int (bool enable)
	Enables/disables the Time Seconds Interrupt. More...

static bool	rtc_hal_read_alarm_int_enable (void)
	Checks whether the Time Alarm Interrupt is enabled/disabled. More...

static void	rtc_hal_config_alarm_int_enable (bool enable)
	Enables/disables the Time Alarm Interrupt. More...

static bool	rtc_hal_read_time_overflow_int_enable (void)
	Checks whether the Time Overflow Interrupt is enabled/disabled . More...

static void	rtc_hal_config_time_overflow_int_enable (bool enable)
	Enables/disables the Time Overflow Interrupt. More...

static bool	rtc_hal_read_time_interval_int_enable (void)
	Checks whether the Time Invalid Interrupt is enabled/disabled. More...

static void	rtc_hal_config_time_interval_int (bool enable)
	Enables/disables the Time Invalid Interrupt. More...

RTC HAL Driver

Overview

The RTC HAL driver initializes the RTC registers and also provides functions to read or modify the RTC registers. These are mostly invoked by the RTC peripheral driver.

User configuration structures

The RTC HAL driver uses an instantiation of the rtc_hal_init_config_t structure, which is passed in by the user, to initialize the RTC registers.This is an example initialization of this structure:

/* rtc hal init */
rtc_hal_init_config_t rtc_init_configs = {
    .enableOscillatorLoadConfg = 2,
    .disableClockOutToPeripheral = false,
    .enable32kOscillator = true,
    .enableWakeupPin = false,
    .startSecondsCounterAt = 0,
    .prescalerAt = 1,
    .alarmCounterAt = 0,
    .compensationInterval = 0,
    .timeCompensation = 0,
    .enableInterrupts = 0,
};

Enable or Disable Alarm Interrupts

The user calls the rtc_hal_config_alarm_int_enable() function to enable or disable the RTC alarm interrupt. The user calls the rtc_hal_read_alarm_int_enable() function to get the state of the RTC alarm interrupt bit.This is an example:

rtc_datetime_t date;
/* alarm with no arguments */
if (rtc_hal_read_alarm_int_enable())
{
    rtc_get_alarm(&date);
    printf("Current alarm: %02d:%02d:%02d\r\n",
                    date.hour, date.minute, date.second);
    return;
}
else
{
    printf("No alarm armed\r\n");
}
rtc_hal_config_alarm_int_enable(true);    

Data Structure Documentation

struct rtc_hal_init_config_t

Data Fields
uint8_t	enableOscillatorLoadConfg
	Configures the oscillator load in pF. More...

bool	disableClockOutToPeripheral
	at register field CR[CLKO]

bool	enable32kOscillator
	After enabling this, waits the oscillator startup time before enabling the time counter TSR[TSR] to allow the 32.768 kHz clock time to stabilize. More...

uint32_t	startSecondsCounterAt
	Sets the register field TSR[TSR]. More...

uint16_t	prescalerAt
	Sets the register field TPR[TPR]. More...

uint32_t	alarmCounterAt
	Sets the register field TAR[TAR]. More...

uint8_t	compensationInterval
	Configures the compensation interval in seconds from 1 to 256 to control how frequently the TCR should adjusts the number of 32.768 kHz cycles in each second. More...

uint8_t	timeCompensation
	Configures the number of 32.768 kHz clock cycles in each second. More...

hw_rtc_ier_t	enableInterrupts
	Sets/clears any of the following bitfields to enable/disable the respective interrupts. More...

Field Documentation

uint8_t rtc_hal_init_config_t::enableOscillatorLoadConfg

Example:
value 0 => to be configured: 0pF
value 2 => to be configured: 2pF
value 4 => to be configured: 4pF
value 8 => to be configured: 8pF
value 16 => to be configured: 16pF
Any other value is ignored.

bool rtc_hal_init_config_t::enable32kOscillator

at register field CR[OSCE]

uint32_t rtc_hal_init_config_t::startSecondsCounterAt

Set to zero to skip this configuration.

uint16_t rtc_hal_init_config_t::prescalerAt

Set to zero to skip this configuration.

uint32_t rtc_hal_init_config_t::alarmCounterAt

Set to zero to skip this configuration.

uint8_t rtc_hal_init_config_t::compensationInterval

The value written should be one less than the number of seconds (for example, write zero to configure for a compensation interval of one second). This register is double-buffered and writes do not take affect until the end of the current compensation interval.
Set to zero to skip this configuration.

uint8_t rtc_hal_init_config_t::timeCompensation

This register is double-buffered and writes do not take affect until the end of the current compensation interval.

80h Time prescaler register overflows every 32896 clock cycles.
... ...
FFh Time prescaler register overflows every 32769 clock cycles.
00h Time prescaler register overflows every 32768 clock cycles.
01h Time prescaler register overflows every 32767 clock cycles.
... ...
7Fh Time prescaler register overflows every 32641 clock cycles.

hw_rtc_ier_t rtc_hal_init_config_t::enableInterrupts

TSIE: Time Seconds Interrupt Enable
TAIE: Time Alarm Interrupt Enable
TOIE: Time Overflow Interrupt Enable
TIIE: Time Invalid Interrupt Enable

For MCUs that have the Wakeup Pin only:
WPON: Wakeup Pin On (see the corresponding MCU's reference manual)

For MCUs that have the Monotonic Counter only:
MOIE: Monotonic Overflow Interrupt Enable

struct rtc_hal_access_control_config_t

Data Fields
hw_rtc_war_t	writeFlags
	Set/clear any of the following bitfields to enable/disable the respective interrupts. More...

hw_rtc_rar_t	readFlags
	Set/clear any of the following bitfields to enable/disable the respective interrupts. More...

Field Documentation

hw_rtc_war_t rtc_hal_access_control_config_t::writeFlags

IERW: Interrupt Enable Register Write
LRW: Lock Register Write
SRW: Status Register Write
CRW: Control Register Write
TCRW: Time Compensation Register Write
TARW: Time Alarm Register Write
TPRW: Time Prescaler Register Write
TSRW: Time Seconds Register Write

For MCUs that have Tamper feature:
TIRW: Tamper Interrupt Register Write
TTRW: Tamper Trim Register Write
TDRW: Tamper Detect Register Write
TERW: Tamper Enable Register Write
TTSW: Tamper Time Seconds Write

For MCUs that have Monotonic Counter:
MCHW: Monotonic Counter High Write
MCLW: Monotonic Counter Low Write
MERW: Monotonic Enable Register Write

hw_rtc_rar_t rtc_hal_access_control_config_t::readFlags

IERR: Interrupt Enable Register Read
LRR: Lock Register Read
SRR: Status Register Read
CRR: Control Register Read
TCRR: Time Compensation Register Read
TARR: Time Alarm Register Read
TPRR: Time Prescaler Register Read
TSRR: Time Seconds Register Read

For MCUs that have Tamper feature:
TIRR: Tamper Interrupt Register Read
TTRR: Tamper Trim Register Read
TDRR: Tamper Detect Register Read
TERR: Tamper Enable Register Read
TTSR: Tamper Time Seconds Read

For MCUs that have Monotonic Counter:
MCHR: Monotonic Counter High Read
MCLR: Monotonic Counter Low Read
MERR: Monotonic Enable Register Read

Function Documentation

void rtc_hal_init ( rtc_hal_init_config_t * configs )

Parameters

configs Pointer to a structure where the configuration details are stored at. The structure values that do NOT apply to the MCU in use are ignored.

static void rtc_hal_reset_reg_TSR ( void )

inlinestatic

static void rtc_hal_reset_reg_TPR ( void )

inlinestatic

static void rtc_hal_reset_reg_TAR ( void )

inlinestatic

static void rtc_hal_reset_reg_TCR ( void )

inlinestatic

static void rtc_hal_reset_reg_CR ( void )

inlinestatic

static void rtc_hal_reset_reg_SR ( void )

inlinestatic

static void rtc_hal_reset_reg_LR ( void )

inlinestatic

static void rtc_hal_reset_reg_IER ( void )

inlinestatic

static void rtc_hal_get_seconds ( uint32_t * seconds )

inlinestatic

Parameters

Seconds [out] pointer to variable where the seconds are stored.

static bool rtc_hal_set_seconds ( const uint32_t * seconds )

inlinestatic

Parameters

seconds [in] pointer to a variable from where to write the seconds.

Returns: true: write success since time counter is disabled. false: write error since time counter is enabled.

static void rtc_hal_get_prescaler ( uint16_t * prescale )

inlinestatic

Parameters

prescale [out] pointer to variable where the prescaler's value is stored.

static bool rtc_hal_set_prescaler ( const uint16_t * prescale )

inlinestatic

Parameters

prescale [in] pointer to variable from where to write the seconds.

Returns: true: set successfull; false: error, unable to set prescaler since the the time counter is enabled.

static void rtc_hal_get_alarm ( uint32_t * seconds )

inlinestatic

Parameters

seconds [out] pointer to a variable where the alarm value in seconds will be stored.

static void rtc_hal_set_alarm ( const uint32_t * seconds )

inlinestatic

Parameters

seconds [in] pointer to variable from where to write alarm value in seconds.

static void rtc_hal_get_comp_intrvl_counter ( uint8_t * counter )

inlinestatic

Parameters

counter [out] pointer to variable where the value is stored.

static void rtc_hal_get_current_time_compensation ( uint8_t * tcValue )

inlinestatic

Parameters

tcValue [out] pointer to variable where the value is stored.

static void rtc_hal_get_compensation_interval ( uint8_t * value )

inlinestatic

The value is the configured compensation interval in seconds from 1 to 256 to control how frequently the time compensation register should adjust the number of 32.768 kHz cycles in each second. The value is one less than the number of seconds (for example. Zero means a configuration for a compensation interval of one second).

Parameters

value [out] pointer to variable where the value is stored.

static void rtc_hal_set_compensation_interval ( const uint8_t * value )

inlinestatic

This configures the compensation interval in seconds from 1 to 256 to control how frequently the TCR should adjust the number of 32.768 kHz cycles in each second. The value written should be one less than the number of seconds (for example, write zero to configure for a compensation interval of one second). This register is double buffered and writes do not take affect until the end of the current compensation interval.

Parameters

value [in] pointer to a variable from where to write the value.

static void rtc_hal_get_time_compensation ( uint8_t * value )

inlinestatic

Parameters

value [out] pointer to variable where the value is stored.

static void rtc_hal_set_time_compensation ( const uint8_t * enable )

inlinestatic

Configuring the number of 32.768 kHz clock cycles in each second. This register is double buffered and writes do not take affect until the end of the current compensation interval.
80h Time prescaler register overflows every 32896 clock cycles.
... ...
FFh Time prescaler register overflows every 32769 clock cycles.
00h Time prescaler register overflows every 32768 clock cycles.
01h Time prescaler register overflows every 32767 clock cycles.
... ...
7Fh Time prescaler register overflows every 32641 clock cycles.

Parameters

enable [in] pointer to variable from where to write the value.

static void rtc_hal_config_osc_2pf_load ( bool enable )

inlinestatic

Parameters

enable true: enables load; false: disables load.

static void rtc_hal_config_osc_4pf_load ( bool enable )

inlinestatic

Parameters

enable true: enables load; false: disables load.

static void rtc_hal_config_osc_8pf_load ( bool enable )

inlinestatic

Parameters

enable true: enables load; false: disables load.

static void rtc_hal_config_osc_16pf_load ( bool enable )

inlinestatic

Parameters

enable true: enables load; false: disables load.

static void rtc_hal_config_clock_out ( bool enable )

inlinestatic

Parameters

enable true: enables clock out; false: disables clock out.

static void rtc_hal_config_oscillator ( bool enable )

inlinestatic

After enablement, wait the oscillator startup time before enabling the time counter to allow the 32.768 kHz clock time to stabilize.

Parameters

enable true: enables oscillator; false: disables oscillator.

static void rtc_hal_configure_update_mode ( bool lock )

inlinestatic

This mode allows the time counter enabled to be written even when the status register is locked. When set, the time counter enable, can always be written if the TIF (Time Invalid Flag) or TOF (Time Overflow Flag) are set or if the time counter enable is clear. For devices with the monotonic counter, it allows the monotonic enable to be written when it is locked. When set, the monotonic enable can always be written if the TIF (Time Invalid Flag) or TOF (Time Overflow Flag) are set or if the monotonic counter enable is clear. For devices with tamper detect, it allows the it to be written when it is locked. When set, the tamper detect can always be written if the TIF (Time Invalid Flag) is clear. Note: Tamper and Monotonic features are not available in all MCUs.

Parameters

lock	true: enables register lock, registers cannot be written when locked; False: disables register lock, registers can be written when locked under limited conditions.

static void rtc_hal_configure_supervisor_access ( bool enable_reg_write )

inlinestatic

        Note: Tamper and Monotonic features are NOT available in all MCUs.

Parameters

enable_reg_write true: enables register lock, Non-supervisor mode write accesses are supported; false: disables register lock, non-supervisor mode write accesses are not supported and generate a bus error.

static void rtc_hal_software_reset ( void )

inlinestatic

This resets all RTC registers except for the SWR bit and the RTC_WAR and RTC_RAR registers. The SWR bit is cleared after VBAT POR and by software explicitly clearing it. Note: access control features (RTC_WAR and RTC_RAR registers) are not available in all MCUs.

static void rtc_hal_software_reset_flag_clear ( void )

inlinestatic

static bool rtc_hal_is_counter_enabled ( void )

inlinestatic

Returns: true: time counter is enabled, time seconds register and time prescaler register are not writeable, but increment; false: time counter is disabled, time seconds register and time prescaler register are writeable, but do not increment.

static void rtc_hal_counter_enable ( bool enable )

inlinestatic

Parameters

enable true: enables the time counter; false: disables the time counter.

static bool rtc_hal_is_alarm_occured ( void )

inlinestatic

Returns: true: time alarm has occurred. false: NO time alarm occurred.

static bool rtc_hal_is_counter_overflow ( void )

inlinestatic

Returns: true: time overflow occurred and time counter is zero. false: NO time overflow occurred.

static bool rtc_hal_is_time_invalid ( void )

inlinestatic

Returns: true: time is INVALID and time counter is zero. false: time is valid.

Reads the value of the RTC Status Register (RTC_SR), field Time Invalid Flag (TIF). This flag is set on the VBAT POR or the software reset. The TSR and TPR do not increment and read as zero when this bit is set. This flag is cleared by writing the TSR register when the time counter is disabled.

static void rtc_hal_config_lock_registers ( hw_rtc_lr_t bitfields )

inlinestatic

Parameters

bitfields [in] configuration flags:
Valid bitfields:
LRL: Lock Register Lock
SRL: Status Register Lock
CRL: Control Register Lock
TCL: Time Compensation Lock
For MCUs that have the Tamper Detect only:
TIL: Tamper Interrupt Lock
TTL: Tamper Trim Lock
TDL: Tamper Detect Lock
TEL: Tamper Enable Lock
TTSL: Tamper Time Seconds Lock
For MCUs that have the Monotonic Counter only:
MCHL: Monotonic Counter High Lock
MCLL: Monotonic Counter Low Lock
MEL: Monotonic Enable Lock

static bool rtc_hal_get_lock_reg_lock ( void )

inlinestatic

Returns: true: lock register is not locked and writes complete normally. false: lock register is locked and writes are ignored.

static void rtc_hal_set_lock_reg_lock ( bool set_to )

inlinestatic

Once cleared, this can only be set by the VBAT POR or the software reset.

Parameters

set_to true: Lock register is not locked and writes complete normally. false: Lock register is locked and writes are ignored.

static bool rtc_hal_get_status_reg_lock ( void )

inlinestatic

Returns: true: Status register is not locked and writes complete normally. false: Status register is locked and writes are ignored.

static void rtc_hal_set_status_reg_lock ( bool set_to )

inlinestatic

Once cleared, this can only be set by the VBAT POR or the software reset.

Parameters

set_to true: Status register is not locked and writes complete normally. false: Status register is locked and writes are ignored.

static bool rtc_hal_get_control_reg_lock ( void )

inlinestatic

Returns: true: Control register is not locked and writes complete normally. false: Control register is locked and writes are ignored.

static void rtc_hal_set_control_reg_lock ( bool set_to )

inlinestatic

Once cleared, this can only be set by the VBAT POR or the software reset.

Parameters

set_to true: Control register is not locked and writes complete normally. false: Control register is locked and writes are ignored.

static bool rtc_hal_get_time_comp_lock ( void )

inlinestatic

Returns: true: Time compensation register is not locked and writes complete normally. false: Time compensation register is locked and writes are ignored.

static void rtc_hal_set_time_comp_lock ( bool set_to )

inlinestatic

Once cleared, this can only be set by the VBAT POR or the software reset.

Parameters

set_to true: Time compensation register is not locked and writes complete normally. false: Time compensation register is locked and writes are ignored.

static void rtc_hal_config_interrupts ( hw_rtc_ier_t * bitfields )

inlinestatic

Parameters

bitfields [in] set/clear respective bitfields to enabled/disabled interrupts.
[out] resulting interrupt enable state.
Valid bitfields:
TSIE: Time Seconds Interrupt Enable
TAIE: Time Alarm Interrupt Enable
TOIE: Time Overflow Interrupt Enable
TIIE: Time Invalid Interrupt Enable

For MCUs that have the Wakeup Pin only:
WPON: Wakeup Pin On (see the corresponding MCU's reference manual)

For MCUs that have the Monotonic Counter only:
MOIE: Monotonic Overflow Interrupt Enable

static bool rtc_hal_read_seconds_int_enable ( void )

inlinestatic

Returns: true: Seconds interrupt is enabled. false: Seconds interrupt is disabled.

static void rtc_hal_config_seconds_int ( bool enable )

inlinestatic

        Note: The seconds interrupt is an edge-sensitive interrupt with a
        dedicated interrupt vector. It is generated once a second and
        requires no software overhead (there is no corresponding status
        flag to clear).

Parameters

enable true: Seconds interrupt is enabled. false: Seconds interrupt is disabled.

static bool rtc_hal_read_alarm_int_enable ( void )

inlinestatic

Returns: true: Time alarm flag does generate an interrupt. false: Time alarm flag does not generate an interrupt.

static void rtc_hal_config_alarm_int_enable ( bool enable )

inlinestatic

Parameters

enable true: Time alarm flag does generate an interrupt. false: Time alarm flag does not generate an interrupt.

static bool rtc_hal_read_time_overflow_int_enable ( void )

inlinestatic

Returns: true: Time overflow flag does generate an interrupt. false: Time overflow flag does not generate an interrupt.

static void rtc_hal_config_time_overflow_int_enable ( bool enable )

inlinestatic

Parameters

enable true: Time overflow flag does generate an interrupt. false: Time overflow flag does not generate an interrupt.

static bool rtc_hal_read_time_interval_int_enable ( void )

inlinestatic

Returns: true: Time invalid flag does generate an interrupt. false: Time invalid flag does not generate an interrupt.

static void rtc_hal_config_time_interval_int ( bool enable )

inlinestatic

Parameters

enable true: Time invalid flag does generate an interrupt. false: Time invalid flag does not generate an interrupt.

Data Structures

Functions

RTC HAL Driver

Overview

User configuration structures

Enable or Disable Alarm Interrupts

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Function Documentation